<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <link rel="STYLESHEET" type="text/css"
 href="../css/site.css">
  <title></title>
</head>
<body>
<div id="page-logo"> <img src="../images/ehcache_logo_trans.gif"
 alt="ehcache" align="left">Constructs Documentation</div>
<div id="page-buttons">
<a href="http://sourceforge.net/projects/ehcache/">Summary</a>&nbsp;|&nbsp;
<a href="http://sourceforge.net/project/admin/?group_id=93232">Admin</a>&nbsp;|&nbsp;
<a href="../"><span class="tabs">Home Page</span></a>&nbsp;|&nbsp; <a
 href="http://sourceforge.net/forum/?group_id=93232">Forums</a>&nbsp;|&nbsp;
<a href="http://sourceforge.net/tracker/?group_id=93232">Tracker</a>&nbsp;|&nbsp;
<a href="http://sourceforge.net/tracker/?group_id=93232">Bugs</a>&nbsp;|&nbsp;
<a href="http://sourceforge.net/tracker/?group_id=93232">Support</a>&nbsp;|&nbsp;
<a href="http://sourceforge.net/tracker/?group_id=93232">Patches</a>&nbsp;|&nbsp;
<a href="http://sourceforge.net/tracker/?group_id=93232">RFE</a>&nbsp;|&nbsp;
<a href="http://sourceforge.net/mail/?group_id=93232">Lists</a>&nbsp;|&nbsp;
<a href="http://sourceforge.net/pm/?group_id=93232">Tasks</a>&nbsp;|&nbsp;
<a href="http://ehcache.sourceforge.net/documentation/">Docs</a>&nbsp;|&nbsp;
<a href="http://sourceforge.net/news/?group_id=93232">News</a>&nbsp;|&nbsp;
<a href="http://sourceforge.net/svn/?group_id=93232">SVN</a>&nbsp;|&nbsp;
<a href="http://sourceforge.net/project/showfiles.php?group_id=93232">Files</a><br>
</div>
For Version 0.5<br>
<br>
<div class="toc">Table of Contents</div>
<ul id="mozToc">
<!--mozToc h1 1 h2 2 h3 3 h4 4--><li><a href="#mozTocId544025">1
Introduction
    </a>
    <ul>
      <li><a href="#mozTocId177637">Constructs</a></li>
      <li><a href="#mozTocId304590">Caching meets
Concurrent Programming
        </a>
        <ul>
          <li><a href="#mozTocId626748">Safety Failures</a></li>
          <li><a href="#mozTocId946646">Liveness Failures</a></li>
        </ul>
      </li>
    </ul>
  </li>
  <li><a href="#mozTocId764933">2 Provided Pattern
Implementations
    </a>
    <ul>
      <li><a href="#mozTocId225705">General Purpose
Caching </a></li>
      <li><a href="#mozTocId997710">Web Caching
        </a></li>
    </ul>
  </li>
  <li><a href="#mozTocId366944">3 Java
Requirements</a></li>
  <li><a href="#mozTocId477330">4 Dependencies</a></li>
  <li><a href="#mozTocId747622">5 Installation
    </a></li>
  <li><a href="#mozTocId265501">6 Logging</a></li>
  <li><a href="#mozTocId430833">7 Obtaining the
Source Code</a>
    <ul>
      <li><a href="#mozTocId688132">Online
        </a></li>
      <li><a href="#mozTocId244950">CVS</a></li>
    </ul>
  </li>
  <li><a href="#mozTocId722946">8 Using The Constructs </a>
    <ul>
      <li><a href="#mozTocId937608">BlockingCache</a>
        <ul>
          <li><a href="#mozTocId159833">Scenario</a></li>
          <li><a href="#mozTocId22662">Solution</a></li>
          <li><a href="#mozTocId659272">Implementation</a></li>
        </ul>
      </li>
      <li><a href="#mozTocId640475">SelfPopulatingCache</a>
        <ul>
          <li><a href="#mozTocId483719">Scenario</a></li>
          <li><a href="#mozTocId598598">Solution</a></li>
          <li><a href="#mozTocId563482">Implementation</a></li>
        </ul>
      </li>
    </ul>
  </li>
</ul>
<br>
<h1><a class="mozTocH1" name="mozTocId544025"></a>1 Introduction<br>
</h1>
Ehcache-constructs provides implementations of common caching patterns.
They can be used as they are or as a starting pointing for custom
caching code. Ehcache-constructs uses ehcache for the backing cache. <br>
<h2><a class="mozTocH2" name="mozTocId177637"></a>Constructs</h2>
Doug Lea in his book <a
 href="http://www.amazon.com/gp/reader/0201310090/ref=sib_dp_pt/104-1236350-6447122#reader-link">Concurrent
Programming in Java</a> talks about concurrency support constructs. One
meaning of a construct is "an abstract or general idea inferred or
derived from specific instances".&nbsp; Just like patterns emerge from
noting the similarities of problems and gradually finding a solution to
classes of them, so to constructs are general solutions to commond
problems. With ehcache-constructs, concrete, extensible implementations
are offered to solve these common problems.<br>
<h2><a class="mozTocH2" name="mozTocId304590"></a>Caching meets
Concurrent Programming<br>
</h2>
All of the constructs use a combination of ehcache and concurrent
programming. As Adam, a friend of mine says, "What could possibly go
wrong?" Well in concurrent programming, the answer is: "A lot".<br>
<br>
(The following section is based on Chapter 1.3 of Doug Lea's&nbsp; <a
 href="http://www.amazon.com/gp/reader/0201310090/ref=sib_dp_pt/104-1236350-6447122#reader-link">Concurrent
Programming in Java</a>). <br>
<br>
There are two often conflicting design goals at play in concurrent
programming. They are:<br>
<ol>
  <li>liveness, where something eventually happens within an activity. <br>
  </li>
  <li>safety, where nothing bad ever happens to an object.</li>
</ol>
<h3><a class="mozTocH3" name="mozTocId626748"></a>Safety Failures</h3>
<br>
Failures of safety include: <br>
<ul>
  <li>Read/Write Conflicts, where one thread is reading from a field
and another is writing to it. The value read depends on who won the
race.</li>
  <li>Write/Write Conflicts, where two threads write to the same field.
The value on the next read is impossible to predict.</li>
</ul>
A cache is similar to a global variable. By its nature it is accessible
to multiple threads. Because caching is often done for performance,
cache entries can be highly contended for.<br>
<br>
<h3><a class="mozTocH3" name="mozTocId946646"></a>Liveness Failures</h3>
<br>
Failures of liveness include:<br>
<ul>
  <li>Deadlock. This is caused by a circular dependency among locks.
The threads involved cannot make progress.</li>
  <li>Missed Signals. A thread entered the wait state after a
notification to wake it up was produced.</li>
  <li>Nested monitor lockouts. A waiting thread holds a lock needed by
a thread wishing to wake it up</li>
  <li>Livelock. A continously retried action continously fails.</li>
  <li>Starvation. Some threads never get allocated CPU time. <br>
  </li>
  <li>Resource Exhaustion. All resourcesof some kind are in use by
threads, none of which will give one up.</li>
  <li>Distributed Failure. A remote machine connected by socket becomes
inaccessible. <br>
  </li>
  <li>Stampede. With notifyAll(), all threads wake up and in a
stampede, attempt to make progress.</li>
</ul>
There are many different failures. Testing for all of them is tedious
and time-consuming. It is sometimes hard to foresee all of them. The
first <code>BlockingCache</code> implementation ran for almost a year
on a very busy application before finally getting overwhelmed. It was
using <code>notifyAll()</code>, and once the load on the cache got
very high indeed, the threads started spending most of their time
stampeding to the object lock and very little time doing anything else.
The result was that server threads went to 1500 and server output
dropped to almost nothing.<br>
<br>
Ehcache-constructs provides high-quality, unit and production-tested
implementations for developers to use.&nbsp; All
released constructs have had a minimum of several months production
use. Some of them have several years of production time. In
addition each one has tests in the test package. These tests include
concurrency and scalability tests. See the tests <a
 href="http://cvs.sourceforge.net/viewcvs.py/ehcache/ehcache/test/java/net/sf/ehcache/constructs/blocking/">here</a>.
<br>
<h1><a class="mozTocH2" name="mozTocId764933"></a>2 Provided Pattern
Implementations<br>
</h1>
<p>At present ehcache-constructs contains:<br>
</p>
<h2><a class="mozTocH3" name="mozTocId225705"></a>General Purpose
Caching <br>
</h2>
<ul>
  <li><a href="index.html#mozTocId937608">BlockingCache</a> - a cache
which blocks subsequent threads until the
first read thread populates a cache entry </li>
  <li><a href="index.html#mozTocId640475">SelfPopulatingCache</a> - a
read-through cache. A cache that
populates elements as they are requested without requiring the caller
to know how the entries are populated. It also enables refreshes of
cache entries without blocking reads on the same entries.</li>
  <li>UpdatingSelfPopulatingCache - a read-through cache. A cache that
populates elements as they are requested without requiring the caller
to know how the entries are populated. The cache entry is automatically
updated on subsequent reads. <br>
  </li>
  <li>SelfPopulatingCollectionsCache - a SelfPopulatingCache that adds
threading safety where it is known in advance that all entries will be
collections.</li>
</ul>
<br>
<ul>
</ul>
<h2><a class="mozTocH3" name="mozTocId997710"></a>Web Caching<br>
</h2>
Servlet 2.3 caching filters that cache HTTP/S responses:<br>
<ul>
  <li>CachingFilter - an abstract, extensible caching filter.<br>
  </li>
  <li>SimplePageCachingFilter - a concrete implementation which caches
pages based on the request URI and Query String.<br>
  </li>
  <li>SimplePageFragmentCachingFilter - a concrete implementation which
caches page fragments based on the request URI and Query String.</li>
</ul>
<ul>
</ul>
<h1><a class="mozTocH2" name="mozTocId366944"></a><span
 style="font-weight: bold;">3 Java
Requirements</span></h1>
Ehcache-constructs supports
JDK1.2, 1.3, 1.4 and 5 at runtime. When compiling from source, the
build
process requires JDK 1.4 or 5. <span><br>
<br>
Ehcache-constructs does not work with JDK1.1.<br>
</span><br>
<span></span>
<h1><a class="mozTocH2" name="mozTocId477330"></a>4 Dependencies</h1>
<span></span>Ehcache-constructs requires:<br>
<ul>
  <li><a href="http://ehcache.sf.net/">ehcache-1.1</a> <br>
  </li>
  <li><a href="http://jakarta.apache.org/commons/logging.html">commons-logging</a>,
from Apache's Jakarta project.</li>
</ul>
<p>In addition For JDK1.2 and JDK
1.3, ehcache requires:</p>
<ul>
  <li>Apache Jakarta's <a
 href="http://jakarta.apache.org/commons/collections.html">commons-collections</a>
(commons-collection.jar),
version 2.1</li>
  <li>Apache <a href="http://xml.apache.org/xerces2-j/">xerces</a>
(xml-apis.jar and xercesImpl.jar), version 2.5</li>
</ul>
The dependencies are also required for ehcache and Hibernate, so if you
already have either of those, your dependency requirements are met.<br>
<br>
The filter constructs are designed to run in a Web Container which
meets the <a href="http://java.sun.com/products/servlet/download.html">Servlet
2.3 specification</a>.<br>
<br>
It has been <a
 href="https://sourceforge.net/tracker/index.php?func=detail&amp;aid=1025128&amp;group_id=93232&amp;atid=603559">reported</a>
that IBM Websphere 5.1 running on IBM JDK1.4 requires
commons-collection.jar even though it does not use it. <br>
<br>
<h1><a class="mozTocH1" name="mozTocId747622"></a>5 Installation<br>
</h1>
The steps are:<br>
<ol>
  <li>Place
the ehcache-constructs-X.X.jar into your classpath. </li>
  <li>Ensure that any libraries required to satisfy <a
 href="file:///wotif/work/ehcache/site/documentation/index.html#dependencies">dependencies</a>
are also in the classpath.</li>
  <li>As an optional step, configure an appropriate <a
 href="file:///wotif/work/ehcache/site/documentation/index.html#logging">logging</a>
level.</li>
</ol>
<h1><a class="mozTocH1" name="mozTocId265501"></a>6 Logging</h1>
Ehcache uses
the Apache Commons Logging library. It acts as a thin bridge between
logging statements in the code and logging infrastructure detected in
the classpath. It will use in order of preference: log4j, JDK1.4
logging and then its own <code>SimpleLog</code> .&nbsp; This enables
ehcache to use logging infrastructures compatible with Java versions
from JDK1.2 to JDK5. It does create a dependency on Apache Commons
Logging, however many projects, including Hibernate, share the same
dependency.<br>
<br>
For normal production use, use the <code>WARN</code> level in log4J
and the <code>WARNING</code> level for JDK1.4 logging.&nbsp; <br>
<h1><a class="mozTocH1" name="mozTocId430833"></a>7 Obtaining the
Source Code</h1>
The source code is distributed in the root directory of the download.
It is called ehcache-constructs-x.x-src.zip. It is also available from
SourceForge
online or through cvs.<br>
<br>
<h2><a class="mozTocH2" name="mozTocId688132"></a>Online<br>
</h2>
The source code can be viewed online via <a
 href="http://cvs.sourceforge.net/viewcvs.py/ehcache/ehcache-constructs/">viewcvs.</a><br>
<h2><a class="mozTocH2" name="mozTocId244950"></a>CVS</h2>
You can check out the sourcecode anonymously using cvs as follows:<br>
<br>
<table>
  <tbody>
    <tr>
      <td> 1. cvs
-d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/ehcache login <br>
2. cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/ehcache co
ehcache-constructs</td>
    </tr>
  </tbody>
</table>
<br>
<h1><a class="mozTocH1" name="mozTocId722946"></a>8 Using The
Constructs <br>
</h1>
In this section each construct is presented in a context of a pattern.<br>
<br>
For each one, there are tests which show further examples of
usage.&nbsp; See the online&nbsp; <a
 href="http://cvs.sourceforge.net/viewcvs.py/ehcache/ehcache-constructs/test/java/net/sf/ehcache/constructs/blocking/">tests</a>.<span
 style="font-weight: bold;"><br>
</span>
<h2><a name="mozTocId937608" class="mozTocH3"></a>BlockingCache</h2>
<h3><a name="mozTocId159833" class="mozTocH4"></a>Scenario</h3>
An expensive operation is required, say rendering a large web page,
which takes 30 seconds. The page is not considered stale until it is 5
minutes old.&nbsp; The page is hit very heavily and will be hit an
average of 20 times per minute each 5 minutes.<br>
<h3><a name="mozTocId22662" class="mozTocH4"></a>Solution</h3>
You could use Cache directly here and do a <a
 href="http://ehcache.sourceforge.net/javadoc/net/sf/ehcache/Cache.html#put%28net.sf.ehcache.Element%29">Cache.put(Element
element)</a> to put it in after rendering and then a <a
 href="http://ehcache.sourceforge.net/javadoc/net/sf/ehcache/Cache.html#get%28java.io.Serializable%29">Cache.get(Serializable
key)</a> to get the cached versions out. This will work quite well.
However once every five minutes the page will expire and it will need
to be re-rendered. In the 30 seconds required to do so, 9 more requests
will come in, each of which will be rendered. After that, the rendered
page will be put in the cache and the cache will be hit with requests.
So rather than doing only 1 render every 5 minutes 10 are required.<br>
<br>
If, instead you use a BlockingCache, when the page is being rendered
the other 9 requests that come in will be blocked. When the first
rendering request finishes, the other 9 requests will be returned the
cached page. This approach only requires 1 render each 5 minutes. <br>
<h3><a name="mozTocId659272" class="mozTocH4"></a>Implementation</h3>
Below is a code fragment showing the semantics for using a
BlockingCache to implement the solution,<br>
<br>
<table>
  <tbody>
    <tr>
      <td><br>
private BlockingCache blockingCache;<br>
      <br>
private PageInfo processRequest(HttpServletRequest request,
HttpServletResponse response) throws Exception {<br>
&nbsp;&nbsp;&nbsp; final String key = calculateKey(request);<br>
&nbsp;&nbsp;&nbsp; PageInfo pageInfo = (PageInfo)
blockingCache.get(key);<br>
&nbsp;&nbsp;&nbsp; if (pageInfo == null) {<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; try {<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
//Page is not cached - build the response, cache it, and send to client<br>
&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; pageInfo =
buildPage(request, response, chain);<br>
&nbsp;&nbsp;&nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
blockingCache.put(key, pageInfo);<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
return pageInfo<br>
&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; } catch (final Throwable throwable) {<br>
&nbsp;&nbsp;&nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; // Must unlock the
cache if the above fails<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
blockingCache.put(key, null);<br>
&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; throw new
Exception("Could not build cached page.", throwable);<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }<br>
}<br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<h2><a name="mozTocId640475" class="mozTocH3"></a>SelfPopulatingCache</h2>
<h3><a class="mozTocH4" name="mozTocId483719"></a>Scenario</h3>
A number of database queries need to be done to build a complicated
collection of value objects to perform a search and generate search
results.&nbsp; A search takes 30 seconds to perform.&nbsp; Search
results can be no staler than 2 minutes. An average of 100 searches
with the same queries are done per minute.<br>
<h3><a class="mozTocH4" name="mozTocId598598"></a>Solution</h3>
A Hibernate&nbsp; <a href="mozTocId182189">Query Cache</a> could be
used. The cache could be configured to expire after two minutes. Once
expired however, in the time taken for the Hibernate Query Cache to
repopulate, 50 searches will have occurred. Over the 2 minutes, out of
200 searches performed, 50 will be uncached.<br>
<br>
A <a href="mozTocId937608">BlockingCache</a> will remove the extra
searches, while the repopulate is being done. The uncached searches
will drop to 1 out of 200. However, all search threads will block while
the repopulate takes place.&nbsp; A user will usually see fast
responses but every two minutes 50 requests will take 30 seconds. <br>
<h3><a class="mozTocH4" name="mozTocId563482"></a>Implementation</h3>
<br>
<ol>
  <li>Extend SelfPopulatingCacheManager </li>
  <li>Create a SelfPopulatingCache </li>
  <li>Create a SelfPopulatingCacheEntryFactory </li>
  <li>Use a thread to call refresh. Perhpas JMX or a timing service
such as Quartz. </li>
  <li>Configure the cache in ehcache.xml. The cache might be external
because it is being refreshed. </li>
</ol>
<br>
<hr><a href="http://sourceforge.net"><img
 style="border: 0px solid ; width: 88px; height: 31px;"
 alt="SourceForge.net" src="../images/sflogo.php.png"></a><br>
<br>
</body>
</html>
